home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 24 / AACD 24.iso / AACD / Programming / cvs-1.11.1 / README.AMIGA < prev    next >
Text File  |  2001-01-01  |  15KB  |  305 lines
  1. CVS 1.11.1p1 Amiga port (28 July 2001)
  2. =======================================
  3.  
  4. Introduction
  5. ------------
  6. This is a somewhat rough port of GNU CVS 1.11.1p1, a version control system, which
  7. allows you to keep old versions of files (usually source code), keep a log of
  8. who, when, and why changes occurred, etc., like RCS or SCCS. It handles
  9. multiple developers, multiple directories, triggers to enable/log/control
  10. various operations, and can work over a wide area network. The following tasks
  11. are not included; they can be done in conjunction with CVS but will tend to
  12. require some script-writing and software other than CVS: bug-tracking, build
  13. management (that is, make and make-like tools), and automated testing. (Quoted
  14. from the CVS documentation.)
  15.  
  16. I call this a 'rough port' since it is not as polished as, say Heinz Wrobel's
  17. excellent 'RCS' port. It does what it needs to do, but a few features are
  18. sorely lacking, such as support for Amiga file protection bits. On the other
  19. hand, however, you get everything, and perhaps more, you got with the previous
  20. Amiga ports of CVS: this port does not require 'ixemul.library' to work and it
  21. does not require an RCS installation as it is completely self contained. The
  22. port also probably would win a price as the largest 'pure' executable; it can
  23. be made resident.
  24.  
  25.  
  26. What's in this package?
  27. -----------------------
  28. This distribution contains the Amiga port, the Amiga specific source code and
  29. most of the original GNU CVS 1.11.1p1 distribution. 'Most' in this case means that
  30. only the original source code has been omitted in order to keep the
  31. distribution archive small; the documentation and support files are all
  32. provided. The original source code can be downloaded from the Internet at
  33. 'ftp://ftp.cvshome.org/pub/cvs-1.11.1p1/cvs-1.11.1p1.tar.gz'. I have added two more
  34. files which are converted from the original Unix man pages, namely 'cvs.1.man'
  35. and 'cvs.5.man' whose sources can be found in the 'cvs-1.11.1p1/man' directory.
  36.  
  37.  
  38. Installation; the easy part
  39. ---------------------------
  40. Almost everything you need to get CVS up and running is contained in the
  41. archive which also included the 'README.AMIGA' file you are currently reading.
  42. And that means the 'cvs' executable. You will also need a working
  43. 'queue-handler' (the one that ships with Workbench 3.1 and beyond is,
  44. unfortunately, broken) which can be found on Aminet (you can find the archive
  45. at 'http://us.aminet.net/pub/aminet/util/sys/HWGQueue.lha'). A TCP/IP stack
  46. like Miami or AmiTCP is supported but not strictly required: you can perfectly
  47. well keep your CVS repository on your local machine. Since CVS may ask you to
  48. edit the log entries associated with the files to store, you may want to
  49. configure the 'EDITOR' environment variable. Last, but not least, you must set
  50. up an environment variable which allows CVS to associate you with the changes
  51. you made; this should be the 'USER', 'LOGUSER' or 'USERNAME' variable.
  52.  
  53. Most importantly, this port requires Kickstart 2.04 or higher.
  54.  
  55. Here is how you could set up CVS on your machine. We start by creating two
  56. drawers on the 'Work:' volume:
  57.  
  58.    MakeDir Work:CVS-Root
  59.    MakeDir Work:CVS-Home
  60.  
  61. Next, we add two lines to the 'S:User-Startup' file:
  62.  
  63.    Assign CVSHOME: Work:CVS-Home
  64.    Path CVSHOME: Add
  65.  
  66. The CVS program will need to be copied:
  67.  
  68.    Copy cvs Work:CVS-Home CLONE
  69.  
  70. And the path to the CVS repository needs to be set:
  71.  
  72.    SetEnv CVSROOT :local:Work:CVS-Root
  73.    Copy ENV:CVSROOT ENVARC:
  74.  
  75. Two environment variables need to be set up. Most importantly, CVS will need
  76. your ID to write it into the log and revision files it creates. The Amiga port
  77. will query three environment variables for that information, in the following
  78. order: 'USER', 'LOGUSER' and 'USERNAME'. This means if the variable 'USER' is
  79. not set, it will proceed to check whether 'LOGUSER' is set, and so forth. You
  80. may have already configured these variables, but if you haven't, I suggest you
  81. set up the 'LOGUSER' variable, like this:
  82.  
  83.    SetEnv LOGUSER <Your ID here>
  84.    Copy ENV:LOGUSER ENVARC:
  85.  
  86. Note that <Your ID here> should be replaced by a mnemonic, nick name or short
  87. name that must not contain any blank space characters.
  88.  
  89. You may want to configure the 'EDITOR' environment variable to invoke your
  90. preferred text editor when CVS requests that log messages are added for an
  91. update. If this variable is not set, CVS will default to invoke the 'Ed'
  92. editor. This can be problematic if you have installed 'CygnusEd' whose 'Ed'
  93. program detaches from the Shell that invoked it. When CVS invokes the editor,
  94. it expects it to return only when the user has finished editing the respective
  95. file. Here is an example configuration for CygnusEd:
  96.  
  97.    SetEnv EDITOR Ed -keepio
  98.  
  99. And here is one for TurboText:
  100.  
  101.    SetEnv EDITOR TTX WAIT
  102.  
  103. Don't forget to save the environment variable setting to make it permanent,
  104. like this:
  105.  
  106.    Copy ENV:EDITOR ENVARC:
  107.  
  108. Finally, install the 'queue-handler' from Aminet and reboot your machine. When
  109. the system is again up and running, initialize the CVS repository like this:
  110.  
  111.    cvs init
  112.  
  113. And that's all. Well, maybe you want to add a few default options to the
  114. configuration file CVS reads upon startup. That file should be placed in the
  115. 'CVSHOME:' directory and called '.cvsrc'.
  116.  
  117.  
  118. Networked operation and SSH
  119. ---------------------------
  120. This CVS port includes built-in remote shell (rsh) and secure shell (ssh)
  121. client code, which allows you to exchange files with networked, non-local CVS
  122. repositories. To use a remote repository, you will need to change the name of
  123. the CVS root directory. For a local repository, you would use the following
  124. commands to set it up, like this:
  125.  
  126.    SetEnv CVSROOT :local:Work:CVS-Root
  127.    Copy ENV:CVSROOT ENVARC:
  128.  
  129. But if the repository were on a remote machine, you would use something like
  130. this:
  131.  
  132.    SetEnv CVSROOT :server:login@host:/usr/local/cvsroot
  133.    Copy ENV:CVSROOT ENVARC:
  134.  
  135. In that example, you would replace 'login' with your account name on the
  136. networked machine called 'host'; the '/usr/local/cvsroot' refers to the fully
  137. qualified name of the CVS root directory. Note that for this to work, you need
  138. to have a shell login account on the remote machine, and that machine must be
  139. configured to allow for remote shell login. As the remote shell login is
  140. rather risky and insecure, most sites will have it disabled. Bad luck, but
  141. there is an alternative: secure shell. This feature allows you to connect to a
  142. remote repository as with a remote shell login, except that the connection is
  143. made in a much secure fashion using encrypted data channels. This process
  144. requires that you have a login password handy, for which the CVS port will
  145. prompt you before it connects to the remote. To activate the secure shell
  146. feature, you would set an environment variable, like this:
  147.  
  148.    SetEnv CVS_RSH ssh
  149.  
  150. This will cause the built-in secure shell (ssh) client to be used in place of
  151. the remote shell (rsh) client. The secure shell client implementation is a
  152. stripped down, simplified version of the real thing, the full-blown version,
  153. which supports more different and more secure encryption algorithms. What this
  154. version can do is just about the bare minimum, which means that it supports
  155. only two block cipher algorithms ('Triple DES' and 'Blowfish') and that the
  156. initial public key exchange is not as fast as it could be. It also only
  157. supports version 1.5 of the secure shell protocol. By default, the ssh client
  158. will resort to 'Triple DES' for encryption and decryption. To choose the
  159. 'Blowfish' algorithm instead (which runs faster than 'Triple DES'), use the
  160. following environment variable:
  161.  
  162.    SetEnv CVS_SSH_CIPHER blowfish
  163.  
  164. Not all secure shell server implementations support the 'Blowfish' algorithm,
  165. but all servers are required to support 'Triple DES'. Thus, if you cannot
  166. connect to a server which aborts the protocol negotiation, it may be that it
  167. does not understand the choice of encryption algorithm.
  168.  
  169. CAUTION: The majority of the CVS documentation I know recommends to use the
  170.          keyword ':ext:' in place of ':server:' for communicating with a
  171.          networked CVS installation -- this will *NOT* work with this Amiga
  172.          port. What does work are the built-in rsh and ssh clients, and these
  173.          require that you use the ':server:' keyword when specifying the name
  174.          of the CVS root directory. Therefore the :ext: method is disabled
  175.          in this port !
  176.  
  177. By default, the SSH client will attempt to connect to the server on port 22.
  178. This not always desirable, especially for custom SSH configurations. You can
  179. override this default choice of the port number using yet another environment
  180. variable, like this:
  181.  
  182.    SetEnv CVS_SSH_PORT 33194
  183.  
  184. Last but not least, a word on data compression. The SSH specification allows
  185. for data to be compressed before it is encrypted. This functionality is not
  186. implemented in the reduced SSH implementation which is part of this Amiga CVS
  187. port. This sounds like a disadvantage, but it need not be. In fact, CVS can
  188. use data compression for data exchange, and the SSH layer on top of it could
  189. not have compressed this data any further. That's entropy for you...
  190.  
  191.  
  192. Usage
  193. -----
  194. I personally found the default CVS documentation to be rather confusing. If
  195. you don't know rather well what CVS is good for, then the examples, the
  196. terminology, all this doesn't seem to make great sense. My introduction to CVS
  197. followed with Karl Fogel's book "Open Source Development with CVS" which
  198. describes in compact form what CVS is and how it may be used. I suggest that
  199. you consult the book (portions of which are available from 'www.coriolis.com')
  200. and/or the CVS documentation (which has been included with this archive in the
  201. 'cvs-1.11/doc' drawer) for hints and ideas on how to use the program. I would
  202. definitely not recommend that you spend any money on the CVS pocket reference
  203. manual written by Gregor N. Purdy, published by O'Reilly until *after* you
  204. have read an introductory book like Karl Fogel's. By its very nature, even a
  205. good pocket reference manual can only refresh your memory on concepts you have
  206. learned before -- if there is nothing to be refreshed in the first place, it
  207. will not be of any help to you.
  208.  
  209. What many people fail to realize and what keeps them from using CVS in place
  210. of the revision control system they have used for years is that you do not
  211. need a networked CVS repository in order to use CVS. A local repository will
  212. do. In fact, I switched over most of my current software development projects
  213. to use a single local repository after I realized that CVS does much better
  214. what I had previously used RCS for.
  215.  
  216. If you need any further documentation or information about CVS you could also
  217. use http://www.cvshome.org/ as a good search path.
  218.  
  219.  
  220. Notes on the implementation
  221. ---------------------------
  222. The Amiga port implements only the client side of the CVS system. This means
  223. that you can check out projects on remote servers but your local Amiga cannot
  224. be a CVS server itself. This feature was omitted deliberately since I could
  225. not find a safe and useful way to make CVS server mode work on the Amiga.
  226. AmigaOS is not a server operating system and shoehorning the code to make it
  227. work somehow would not have helped. If you need a CVS server, try a dedicated
  228. solution using, for example, 'NetBSD'. The Amiga port can communicate with the
  229. server using the remote shell (rsh) and secure shell (ssh) protocols, and I
  230. have verified that the process works reasonably well with, for example, the
  231. public 'Samba' CVS repository.
  232.  
  233. CVS does not have a very sophisticated porting layer. Its file name semantics
  234. all stem from the Unix world and the 'OS/2', 'VMS' and 'Windows NT' ports
  235. merely resort to flipping slashes in file names, if necessary, when it comes to
  236. make a name fit the local system's semantics. I had to find a similar way to
  237. make the semantics work on the Amiga. What I did was to add a translation
  238. service in the Amiga specific code which knows how to translate names like '.'
  239. or '..'. But that's where it ends. Any more sophisticated naming schemes like
  240. 'foo/.././bar' may fail to translate properly. But then, those complex
  241. patterns should be pretty rare anyway.
  242.  
  243. Unlike Heinz Wrobel's excellent 'RCS' port, this CVS port does not preserve
  244. Amiga file protection bits for files checked in. When you check in a project
  245. and check it out again, all file and directory protection bits will default to
  246. 'rwed', losing the 'archived', 'pure' and 'script' bits.
  247.  
  248. The Amiga port will expand wild card patterns for file and directory names
  249. specified as command line parameters, such as "#?.c". The wild card pattern
  250. syntax is that of AmigaDOS. It is *not* the syntax of the standard regular
  251. expressions other GNU tools will use.
  252.  
  253. You can access remote CVS repositories by means of a properly configured
  254. TCP/IP stack. This port requires that the stack complies to the AmiTCP V3 API
  255. definition, which all modern Amiga TCP/IP stacks do. It does not work with the
  256. INet-225 TCP/IP stack, though.
  257.  
  258. When CVS resorts to calling external programs, a working 'PIPE:' device is
  259. required, which is not yet part of the AmigaOS Workbench distribution. Do not
  260. underestimate this. The program will fail or behave erratically without a
  261. working 'PIPE:' device. It is strongly recommended to download a working
  262. 'queue-handler', such as from Aminet.
  263.  
  264. The source code for the Amiga port is included in this distribution. All you
  265. need to know before you can recompile this CVS port is described in the file
  266. 'README.AMIGA' which you can find in the 'source' directory.
  267.  
  268. This is a 'single user' CVS port. There is just one single home directory
  269. (referred to as 'CVSHOME:') and your login name and ID are assumed to be the
  270. same (set in the 'USER', 'LOGUSER' or 'USERNAME' environment variables).
  271.  
  272. There is no 'cvsbug' shell script or program included with this port.
  273.  
  274.  
  275. Known problems and issues
  276. -------------------------
  277. It is known that a wrong set TimeZone "ENVARC:TZ" variable could cause
  278. problems while working with CVS. Please make sure that you use a proper time
  279. value in TZ. Something like "0200" for +2 GMT should be fine.
  280.  
  281. Another issue that can produce problems while working with cvs on Amiga is when
  282. you are using remote respositories (:pserver: or :server: method) and in this
  283. repositories are files with larger filenames than your filesystem on your
  284. checkout directory support. This filenames will be truncated to the maximum
  285. size that is allowed. This will cause that you cannot checkin this files again!
  286.  
  287.  
  288. Contacting the authors
  289. ----------------------
  290. If you have any further questions on this port, feel free to contact us:
  291.  
  292.    Olaf Barthel
  293.    Brabeckstr. 35
  294.    D-30559 Hannover
  295.    Federal Republic of Germany
  296.  
  297.    olsen@sourcery.han.de
  298.  
  299.    Jens Langner
  300.    Lannerstrasse 1
  301.    D-01219 Dresdem
  302.    Federal Republic of Germany
  303.  
  304.    Jens.Langner@htw-dresden.de
  305.